home *** CD-ROM | disk | FTP | other *** search
/ IRIX Base Documentation 1998 November / IRIX 6.5.2 Base Documentation November 1998.img / usr / share / catman / u_man / cat1 / ar.z / ar
Text File  |  1998-10-30  |  16KB  |  331 lines
  1.  
  2.  
  3.  
  4. AAAARRRR((((1111))))                                                                    AAAARRRR((((1111))))
  5.  
  6.  
  7.  
  8. NNNNAAAAMMMMEEEE
  9.      ar - archive and library maintainer
  10.  
  11. SSSSYYYYNNNNOOOOPPPPSSSSIIIISSSS
  12.      ar -d [-lv] archive file ...
  13.      ar -m [-lv] [-abi] [posname] archive file ...
  14.      ar -p [-ls]  archive [file ...]
  15.      ar -q [-clzf]  archive file ...
  16.      ar -r [-cuvsfl] [-abi] [posname] archive file ...
  17.      ar -t [-vs] archive [file ...]
  18.      ar -x [-vosCT] archive [file ...]
  19.  
  20. DDDDEEEESSSSCCCCRRRRIIIIPPPPTTTTIIIIOOOONNNN
  21.      The archiver (aaaarrrr) maintains groups of files as a single archive file.
  22.      Generally, you use this utility to create and update library files that
  23.      the link editor uses; however, you can use the archiver for any similar
  24.      purpose.
  25.  
  26.      This version of aaaarrrr produces both 32-bit and 64-bit archives.  The 32-bit
  27.      archive format is defined in the System V Release 4 ABI.  The 64-bit
  28.      archive format is defined in the 64-bit ELF OBJECT File Specification.
  29.      32-bit objects and 64-bit objects cannot be mixed in an archive.  The
  30.      first object determines whether the archive will be 32-bit or 64-bit, if
  31.      the archive does not exist to begin with.  In compilers of version 7.x
  32.      and higher, the archiver also archives WHIRL objects.  Mixing is allowed
  33.      between 32-bit relocatable ELF objects and 32-bit WHIRL objects, and
  34.      between 64-bit relocatable ELF objects and 64-bit WHIRL objects.
  35.      Different versions of WHIRL objects are NOT mixable.
  36.  
  37.      If the environment variable _XPG is defined, _a_r operates in conformance
  38.      with the X/Open XPG4 specifications.  The format of the output may differ
  39.      in accordance to the XPG4 standards.  Changes are either in the exit
  40.      status or the format of the output.
  41.  
  42.      Any option that changes an object library causes the archive-symbol-table
  43.      to be updated.  This makes adding one file at a time to a library very
  44.      slow.
  45.  
  46.      Useless options (such as using option ----uuuu with option ----tttt) are not
  47.      diagnosed.  NNNNOOOOTTTTEEEE:::: aaaarrrr uses a portable ASCII-format archive that you can
  48.      use on various machines that run UNIX.
  49.  
  50.      Options are documented here with a leading hyphen(-) form.  An older form
  51.      with all option letters together and no leading hyphen is still
  52.      supported.  The first example below shows the old form.
  53.  
  54.      Examples:
  55.      ar cr lib.a a.o b.o
  56.      ar -c -r lib.a a.o b.o
  57.      ar -cr lib.a a.o b.o
  58.  
  59.  
  60.  
  61.  
  62.  
  63.                                                                         PPPPaaaaggggeeee 1111
  64.  
  65.  
  66.  
  67.  
  68.  
  69.  
  70. AAAARRRR((((1111))))                                                                    AAAARRRR((((1111))))
  71.  
  72.  
  73.  
  74.      Options are:
  75.  
  76.      ----aaaa   Position new files in the archive after the file named by the
  77.           _p_o_s_n_a_m_e operand.  Use this suboption with the mmmm or rrrr options.
  78.  
  79.      ----bbbb   Position new files in the archive before the file named by the
  80.           _p_o_s_n_a_m_e operand.  Use this suboption with the mmmm or rrrr options.
  81.  
  82.      ----cccc   Suppress the normal message that the archiver prints when it creates
  83.           the archive file _a_r_c_h_i_v_e. Normally, the archiver creates the
  84.           specified archiver file when it needs to.
  85.  
  86.      ----CCCC   Prevent extracted files from replacing like-named files in the file
  87.           system.  This option is useful when ----TTTT is also used, to prevent
  88.           truncated names from replacing files with the same prefix.
  89.  
  90.      ----dddd   Delete the specified _f_i_l_es from _a_r_c_h_i_v_e.
  91.  
  92.      ----iiii   Position new files in the archive before the file named by the
  93.           _p_o_s_n_a_m_e operand (equivalent to ----bbbb).  Use this suboption with the ----mmmm
  94.           or ----rrrr options.
  95.  
  96.      ----ffff   Adds padding to the end of each object file archived, using the
  97.           character '\0'.  This enables the loader (lllldddd) to have faster access
  98.           to members in the archive while performing static linking. _W_a_r_n_i_n_g:
  99.           this option results in the change in size of files permanently,
  100.           normally increased by 1 to 15 bytes.  In compiler releases 7.1 and
  101.           higher, this option is the default.
  102.  
  103.      ----llll   Puts temporary files in the local directory. If option ----llll is not
  104.           supplied and the environment variable TTTTMMMMPPPPDDDDIIIIRRRR is defined then
  105.           TTTTMMMMPPPPDDDDIIIIRRRR's value is used as the name of the directory for temporary
  106.           files.  If neither option ----llll nor TTTTMMMMPPPPDDDDIIIIRRRR is supplied, the archiver
  107.           puts its temporary files in the directory /_t_m_p.
  108.  
  109.      ----mmmm   Moves the specified files to the end of the archive.  If you specify
  110.           a positioning character, you must also specify the _p_o_s_n_a_m_e (as in
  111.           option ----rrrr)))) to tell the archiver where to move the files.
  112.  
  113.      ----oooo   Force each newly created file to have the `last modified' date that
  114.           it had before it was extracted from the archive.
  115.  
  116.      ----pppp   Prints the contents of the _f_i_l_es from _a_r_c_h_i_v_e to the standard
  117.           output.  If no _f_i_l_e_s are specified, the contents of all files in the
  118.           archive will be written in the order of the archive.
  119.  
  120.      ----qqqq   Append the specified files to the end of the archive file.  The
  121.           archiver does not accept suboption positioning characters with the
  122.           ----qqqq option.  It also does not check whether the files you want to add
  123.           already exist in the archive.  This is useful to bypass the
  124.           searching otherwise done when creating a large archive piece by
  125.           piece.  Since the archive-symbol-table of an object library is
  126.  
  127.  
  128.  
  129.                                                                         PPPPaaaaggggeeee 2222
  130.  
  131.  
  132.  
  133.  
  134.  
  135.  
  136. AAAARRRR((((1111))))                                                                    AAAARRRR((((1111))))
  137.  
  138.  
  139.  
  140.           updated with ----qqqq it is advisable to add as many files as possible in
  141.           one execution of _a_r.  Only ----qqqqzzzz (see ----zzzz below) avoids quadratic
  142.           behavior when creating a large object archive piece by piece.
  143.  
  144.      ----rrrr   Replace or add _f_i_l_es to _a_r_c_h_i_v_e.  If the archive named by _a_r_c_h_i_v_e
  145.           does not exist, a new archive file will be created and a diagnostic
  146.           message will be written to standard error (unless the ----cccc option is
  147.           specified).  If no _f_i_l_es are specified and the _a_r_c_h_i_v_e exists,
  148.           nothing is done.  Files that replace existing files will not change
  149.           the order of the archive.  If you use the suboption ----uuuu with ----rrrr,,,, the
  150.           archiver only replaces those files that have `last-modified' dates
  151.           later than the archive files.  If you use a positioning character
  152.           (from the set aaaabbbbiiii)))) you must specify the _p_o_s_n_a_m_e argument to tell the
  153.           archiver to put the new files after (aaaa) or before (bbbb or iiii).
  154.           Otherwise, the archiver puts new files at the end of the archive.
  155.  
  156.      ----ssss   Makes an archive-symbol-table file in the archive.  The ----ssss option is
  157.           automatically added when any of the options ----dddd, ----mmmm, or ----rrrr is
  158.           requested.
  159.  
  160.           If you specify ----ssss, the archiver creates the archive-symbol-table
  161.           file as its last action before finishing execution.  You must
  162.           specify at least one other archive option (mmmm, pppp, dddd, rrrr, or tttt) when
  163.           you use the ----ssss option.
  164.  
  165.      ----tttt   Write a table of contents for the files in _a_r_c_h_i_v_e to the standard
  166.           output.  If you don't specify any file names, write a table of
  167.           contents for all files in the order of the archave.  If you specify
  168.           file names, the archiver writes a table of contents only for those
  169.           files.
  170.  
  171.      ----TTTT   Allow filename truncation of extracted files whose archive names are
  172.           longer than the file system can support.  By default, extracting a
  173.           file with a name that is too long is an error; a diagnostic message
  174.           will be written and the file will not be extracted.
  175.  
  176.      ----uuuu   Update older files.  When used with the ----rrrr option, files within the
  177.           archive will be replaced only if the corresponding _f_i_l_e is newer
  178.           than the existing _a_r_c_h_i_v_e file. This option uses the UNIX system
  179.           `last-modified' date for this comparison. ----uuuu gives no warning when
  180.           replacement is refused.
  181.  
  182.      ----vvvv   Gives a verbose file-by-file description as the archiver makes a new
  183.           archive file from an old archive and its constituent files.  When
  184.           you use this option with ----tttt,,,, the archiver lists, on standard output,
  185.           all information about the files in the archive.  When you use this
  186.           option with ----pppp, the archiver writes the name of the file to standard
  187.           output before writing the file itself to standard output.  If you
  188.           add a second ----vvvv additional informational messages can appear.
  189.  
  190.  
  191.  
  192.  
  193.  
  194.  
  195.                                                                         PPPPaaaaggggeeee 3333
  196.  
  197.  
  198.  
  199.  
  200.  
  201.  
  202. AAAARRRR((((1111))))                                                                    AAAARRRR((((1111))))
  203.  
  204.  
  205.  
  206.      ----xxxx   Extract the files named by the _f_i_l_e operands from the _a_r_c_h_i_v_e.  The
  207.           contents of the archive file will not be changed.  If you don't
  208.           specify any file names, the archiver extracts all files.  Normally,
  209.           the `last-modified' date for each extracted file shows the date when
  210.           someone extracted it; however, when you use ----oooo,,,, the archiver resets
  211.           the `last-modified' date to the date recorded in the archive.
  212.  
  213.      ----zzzz   Only be useful with ----qqqq.  ----qqqqzzzz supresses updating of the archive-
  214.           symbol-table and updates the archive in-place.  The resulting
  215.           archive cannot be used with _l_d (and is not a System V Release 4 ABI
  216.           compliant archive) until an archive-symbol-table update is done.
  217.           _l_d(1) will fail with a message suggesting use of aaaarrrr ----ttttssss if the last
  218.           change to the archive uses ----qqqqzzzz:  Use of ----qqqqzzzz is discouraged: the
  219.           updates are not checked for duplications and in case of a file or
  220.           other error the archive may be destroyed.  If any file name added is
  221.           longer than 15 characters, line _q_z updates the archive-symbol-table
  222.           even with ----qqqqzzzz.  If all file names added with qqqqzzzz on a particular
  223.           execution are 15 characters or less the archive-symbol-table update
  224.           is suppressed (even if some file names already in the archive are
  225.           longer than 15 characters).  xxxx option.
  226.  
  227. FFFFIIIILLLLEEEESSSS
  228.      /tmp/ar.tmp.v* or TMPDIR/ar.tmp.v* temporaries
  229.  
  230. SSSSEEEEEEEE AAAALLLLSSSSOOOO
  231.      lorder(1), ld(1), ar(4)
  232.  
  233.      System V Application Binary Interface, ISBN 0-13-877598-2, Prentice Hall
  234.  
  235. NNNNOOOOTTTTEEEESSSS
  236.      There is no _r_a_n_l_i_b program in IRIX.  Option ----ssss creates the archive-
  237.      symbol-table _l_d uses.
  238.  
  239.      Options ----rrrr, ----dddd, ----mmmm, and ----qqqq imply option ----ssss.  Since option ----ssss creates an
  240.      archive-symbol-table, creating an object library by executing _a_r once per
  241.      object file will be very slow.  Creating an object library with a single
  242.      execution of _a_r is much faster.
  243.  
  244. DDDDIIIIAAAAGGGGNNNNOOOOSSSSTTTTIIIICCCCSSSS
  245.      xxxxxxxxxxxxxxxxxxxx nnnnooootttt ffffoooouuuunnnndddd
  246.           The file xxxxxxxxxxxxxxxxxxxx was not found in the archive.  It could mean a simple
  247.           misspelling, but it could also mean that you supplied xxxxxxxxxxxxxxxxxxxx more
  248.           than the number of times xxxxxxxxxxxxxxxxxxxx appears in the archive!  Files not
  249.           found change the exit code from _a_r but any attempted update of the
  250.           archive (by option rrrr for example) is not suppressed.
  251.  
  252.      nnnnooootttt iiiinnnn aaaarrrrcccchhhhiiiivvvveeee ffffoooorrrrmmmmaaaatttt
  253.              You probably forgot to specify the archive name in the command.
  254.              The _a_r_c_h_i_v_e mentioned in the synopsis should be the archive name.
  255.  
  256.  
  257.  
  258.  
  259.  
  260.  
  261.                                                                         PPPPaaaaggggeeee 4444
  262.  
  263.  
  264.  
  265.  
  266.  
  267.  
  268. AAAARRRR((((1111))))                                                                    AAAARRRR((((1111))))
  269.  
  270.  
  271.  
  272.      The diagnostics "s - creating Symbol hash table" and "s - done" are no
  273.      longer emitted when ----vvvv is used (to make the -v output standard-
  274.      conforming).  If you really want to see those messages, add a second v,
  275.      as in ----vvvvvvvv.
  276.  
  277. MMMMOOOORRRREEEE NNNNOOOOTTTTEEEESSSS
  278.      The behavior documented in this section is not guaranteed to remain the
  279.      same across releases.  This section is provided as help in case _a_r does
  280.      something surprising.
  281.  
  282.      If there is only one hard link (ie, at most one non-symbolic-link. see
  283.      _l_n(2)) to an archive which is being updated then an old archive contents
  284.      are replaced by the new contents by _r_e_n_a_m_e(2).  Otherwise, when updating,
  285.      replacement is by copying the new data onto the old file.  If the archive
  286.      is updated, the replacement archive is built in the same directory as the
  287.      named archive (after following symbolic links to the location of the
  288.      named archive).
  289.  
  290.      In case the copy operation mentioned above is interrupted in mid-copy
  291.      (which is normally not possible) _a_r will attempt to set the archive
  292.      length to 0 and the modification-date to January 1, 1970 as a hint that
  293.      the archive is not usable.
  294.  
  295.      If the _a_r command results in an unchanged archive, the old archive will
  296.      not be replaced.  This is best achieved with, for example, _a_r _r_u _l_i_b._a
  297.      _x._o; if the named object file is not put into the archive, the archive is
  298.      not modified.  The definition of unchanged is very conservative:  _a_r _r
  299.      _l_i_b._a _x._o, for example,  always changes the archive since x.o is added or
  300.      replaced (even though x.o itself may be unchanged).
  301.  
  302.      The following is a sampling of traditional _a_r behaviors that you may find
  303.      surprising.
  304.  
  305.      If you specify the same file twice in an argument list, it can appear
  306.      twice in the archive file.
  307.  
  308.      The oooo option does not change the `last-modified' date of a file unless
  309.      you own the extracted file or you are the super-user.
  310.  
  311.      Trailing slashes are removed from file-path-names.  Only the final
  312.      component of a file-path-name is recorded in an archive.  For example, in
  313.      /a/b/c/dfile////  the file searched for is /a/b/c/dfile and the name
  314.      recorded in the archive is dfile.
  315.  
  316.      If you give _a_r the same name twice in an ar x command the second instance
  317.      of the name will provoke a ``not found'' message.
  318.  
  319.  
  320.  
  321.  
  322.  
  323.  
  324.  
  325.  
  326.  
  327.                                                                         PPPPaaaaggggeeee 5555
  328.  
  329.  
  330.  
  331.